Amazon API Gatewayの「HTTP API」へのマイグレーション #reinvent
Amazon API Gatewayの新機能「HTTP API」
re:Invent 2019期間中、Amazon API Gatewayの新機能「HTTP API」が発表されました。現在プレビューとして、US East (Ohio), US East (N. Virginia), US West (N. California), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo), EU (Frankfurt), EU (Ireland)で提供されています。
本記事では以下のドキュメントに記載されているHTTP APIへのマイグレーション方法を確認したいと思います。
本記事はプレビュー版として公開されているドキュメントを参考にした考察です。本リリース時には仕様などが変わる可能性がありますのでご容赦ください。
OpenAPI 3.0の定義ファイルからインポート可能
HTTP APIはOpenAPI 3.0の定義ファイルからのインポートをサポートしています。REST APIからHTTP APIへのマイグレーションを行いたい場合は、構築済みのREST APIをOpenAPI 3.0形式の定義ファイルをエクスポートする必要があります。
REST APIのOpenAPI 3.0定義ファイルのエクスポート
REST APIのエクスポートは多機能で、様々なユースケースをサポートしています。OpenAPI 3.0定義ファイルのエクスポートももちろん手厚くサポートされています。
エンドポイントは以下のようになります。
https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30
JSON形式でダウンロードしたい場合、以下のようにリクエストします。
$ curl -XGET https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30 \ -H 'Host: apigateway.<region>.amazonaws.com' \ -H 'Accept: application/json'
インポート方法
インポート方法は簡単で、以下のようなCLIコマンドを実行するだけです。api-definition.json は前述しているエクスポートしたファイルを指定します。
$ aws apigatewayv2 import-api --body file://api-definition.json
インポートについての3つのバリデーション情報
インポートを行うと、APi Gatewayは3つのカテゴリのバリデーション情報を提供してくれます。
Info
PropertyはOpenAPIの仕様としては正しいですが、HTTP APIではサポートされていません。
たとえば次の例です。
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
HTTP APIはリクエストのバリデーションをサポートしていないため、インポートに関する情報を生成します。API GatewayはrequestBodyおよびschemaフィールドを無視します。
Warning
OpenAPI仕様ではPropertyまたはStructureは無効ですが、APIの作成は行われます。インポート時にこれが検出された場合、これらの警告を無視してAPIの作成を続行するか、APIの作成を停止するかを指定できます。
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
Error
定義ドキュメントがOpenAPI仕様上が無効であるか、インポートの形式が正しくない場合、API Gatewayはリソースを作成できません。その場合はインポートが失敗するため、エラー内容を修正してから再試行する必要があります。
例えば次の例はOpenAPI 2.0仕様を使っていますが、HTTP APIはOpenAPI 3.0仕様のみをサポートするため、次のAPI定義はインポート時にエラーを生成します。
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
まとめ
OpenAPI 3.0のおかげで、簡単にエクスポート/インポートが行えることが分かりました。移行を考えられている際はぜひ参考にしてください。
